前兩篇把 Analysis Optimization 拆成：

Check
→ Rewrite
→ Validation

Validation 通過後，candidate 才會變成新的 Analysis version。

但接下來還有一個問題：

現在這次 Run，到底跑的是哪一版 Analysis？

所以 Analysis 不只是要 Save，還需要 Versioning。

同一個 Analysis，可以有多個 Version

第一次 Save：

• id = median-session-length
• version = 1

之後 recipe 被修改：

• SQL changed
• script changed
• outputs changed

不會直接 overwrite v1，而是：

v1
↓
change
↓
v2

Analysis 的 id 不變，但 version 會增加。

一個 Version 對應固定 Recipe

這裡要保持一個 invariant：

Analysis Version
=
Inputs
+
SQL
+
Script
+
Outputs

也就是：

• v1 永遠對應 recipe A
• v2 永遠對應 recipe B
• recipe 一旦改變，就要產生新 version

這樣 Run history 才有辦法重現。

如果看到：

Run #42
Version 2

就能確定當時跑的是哪一份 SQL / script。

Version 要記住為什麼被建立

只有：

v1
v2
v3

還不夠。

新的 version 還需要知道：

• from_version
• kind
• reason
• sources
• run
• conversation
• results_check

例如上一篇的 optimization：

v1
↓
events_enterprise
↓
data_movement
↓
Optimize
↓
Validation passed
↓
v2

所以 v2 可以記住：

• 從 v1 來
• 問題是 data_movement
• 是哪個 datasource 觸發
• 哪次 run 發現問題
• 哪個 optimization conversation 做了 rewrite
• validation 結果

這樣之後看到 v2，不只是知道它比較新，也知道它為什麼存在。

Run 也要記 Version

每一次 Run 會記：

• analysis_id
• version
• datasource
• status
• outputs
• measurements

例如：

Run A
→ v1
→ events
→ done

Run B
→ v1
→ events_enterprise
→ needs_optimization

Run C
→ v2
→ events_enterprise
→ done

這樣就能一路追：

Result
↓
Run
↓
Version
↓
Recipe

舊 Version 不會被蓋掉

建立 v2 時，v1 會保留。

目前結構概念上是：

analysis.json
→ current version

versions/
├── 1.json
├── 2.json
└── ...

所以可以直接 compare：

v1
→ raw rows → Python aggregate

v2
→ SQL aggregate → few rows

這對 debug 很重要。

如果新 version 有問題，可以回頭看：

• 哪個 version 開始出現差異
• SQL 改了什麼
• script 改了什麼
• 當時為什麼要改

Conversation 和 Analysis 是兩條不同的 History

Conversation 記的是：

• user 說了什麼
• Agent 怎麼 reasoning / tool call
• optimization 過程

Analysis lineage 記的是：

• v1
• v2
• v3
• 每次 recipe change 的原因

兩者可以連起來，但用途不同。

例如：

Analysis v2
→ created by optimization conversation X

之後可以從 Analysis 找回：

• 為什麼改
• Agent 做了什麼
• Validation 有沒有通過

但真正 Run Analysis 時，不需要 replay conversation。

Versioning 是後面 Scale 的基礎

做到這裡，一個 Analysis 已經有：

• Stable ID
• Versioned Recipe
• Run History
• Change Reason
• Validation Result
• Lineage

下一步就可以開始處理：

同一份 Analysis
→ 多份 datasource
→ 多次 execution

下一篇：

Batch Execution